---
title: Patrol tags
---

Patrol tags allow you to organize and selectively run your patrol tests. You can assign tags to individual tests and then use those tags to filter which tests to run or exclude.
By design, patrol tags should work the same as flutter test tags.

## Defining tags in tests

You can assign tags to your Patrol tests using the `tags` parameter. Tags are defined as a list of strings:

```dart title="patrol_test/example_test.dart"
import 'package:flutter/material.dart';
import 'package:patrol/patrol.dart';

void main() {

  patrolTest(
    'short test with two tags',
    tags: ['smoke', 'regression'],
    ($) async {
      await createApp($);

      await $(FloatingActionButton).tap();
      expect($(#counterText).text, '1');
      await $(FloatingActionButton).tap();
      expect($(#counterText).text, '2');
    },
  );

  patrolTest(
    'short test with tag',
    tags: ['smoke'],
    ($) async {
      await createApp($);

      await $(FloatingActionButton).tap();
      expect($(#counterText).text, '1');

      await $(#textField).enterText('Hello, Flutter!');
      expect($('Hello, Flutter!'), findsOneWidget);
    },
  );
}
```

## Running tests with tags

Use the `--tags` option to run only tests that have specific tags:

```bash
# Run tests with the 'smoke' tag
patrol test --tags smoke

# Run tests with either 'smoke' or 'regression' tag
patrol test --tags='smoke||regression'

# Run tests with both 'login' and 'smoke' tags
patrol test --tags='(login && smoke)'
```

## Excluding tests with tags

Use the `--exclude-tags` option to exclude tests that have specific tags:

```bash
# Exclude tests with the 'regression' tag
patrol test --exclude-tags regression

# Exclude tests with either 'smoke' or 'regression' tag
patrol test --exclude-tags='(smoke||regression)'
```

## Tag expression syntax

Patrol supports complex tag expressions using logical operators:

### Basic operators

- `||` - OR operator (run tests with either tag)
- `&&` - AND operator (run tests with both tags)
- `!` - NOT operator (exclude tests with this tag)

<Warning>Note that tags must be valid Dart identifiers, although they may also contain hyphens.</Warning>
For more information about tag rules, see: https://pub.dev/packages/test#tagging-tests

### Examples

```bash
# Run tests that have either 'smoke' OR 'regression' tag
patrol test --tags='smoke||regression'

# Run tests that have BOTH 'login' AND 'smoke' tags
patrol test --tags='(login && smoke)'

# Run tests with 'payment' OR 'navigation' tag, but NOT 'regression'
patrol test --tags='(payment || navigation) && !regression'

# Combine --tags with --exclude-tags
patrol test --tags='smoke||regression' --exclude-tags='slow'

# Complex expression: (login OR payment) AND (smoke OR regression)
patrol test --tags='((login || payment) && (smoke || regression))'
```

## Combining with other options

You can combine tag filtering with other Patrol CLI options:

```
patrol test --target patrol_test/login_test.dart --tags smoke
```
